Libris Britannia 4/science library(b).zip/science library(b)/DJGPP/DJ111M2.ZIP/docs/djgpp/libc-i-m.tex

Text File | 1994-01-08 | 28KB | 1,220 lines

@c ----------------------------------------------------------------------
@node index, initstate, htons, Alphabetical List

@heading @code{index}
@subheading Syntax

@example
#include <strings.h>

char *index(const char *string, int ch);
@end example

@subheading Description

Returns a pointer to the first occurrence of @var{ch} in @var{string}.
Note that the @code{NULL} character counts, so if you pass zero as
@var{ch} you'll get a pointer to the end of the string back.

@subheading Return Value

A pointer to the character, or @code{NULL} if it wasn't found.

@subheading Example

@example
if (index(path, '*'))
  do_wildcards(path);
@end example

@c ----------------------------------------------------------------------
@node initstate, insque, index, Alphabetical List

@heading @code{initstate}
@subheading Syntax

@example
#include <std.h>

char *initstate(unsigned int seed, char *state, int n);
@end example

@subheading Description

This function fully initializes the random number generator
(@xref{random}).  For more information on the random number generator,
consult the source code @file{libsrc/c/gen/random.c}.

@subheading Return Value

A pointer to the old state.

@c ----------------------------------------------------------------------
@node insque, int86, initstate, Alphabetical List

@heading @code{insque}
@subheading Syntax

@example
void insque(struct vaxque *elem, struct vaxque *prev);
@end example

@subheading Description

Given a queue of elements derived from this structure:

@example
struct vaxque @{
  struct vaxque *vq_next;
  struct vaxque *vq_prev;
@};
@end example

This function inserts a new element @var{elem} in the queue after the
element specified (@var{prev}).  This function emulates the VAX
@code{insque} opcode.  @xref{remque}

@subheading Return Value

None.

@c ----------------------------------------------------------------------
@node int86, int86x, insque, Alphabetical List

@heading @code{int86}
@subheading Syntax

@example
#include <dos.h>

int int86(int ivec, union REGS *in, union REGS *out);
@end example

@subheading Description

This function is just like @code{int86x} (@xref{int86x}) except that
suitable default values are used for the segment registers.

@subheading Return Value

The returned value of @code{EAX}.

@subheading Example

@example
union REGS r;
r.x.ax = 0x0100;
r.h.dl = 'c';
int86(0x21, &r, &r);
@end example

@c ----------------------------------------------------------------------
@node int86x, intdos, int86, Alphabetical List

@heading @code{int86x}
@subheading Syntax

@example
#include <dos.h>

int int86x(int ivec, union REGS *in, union REGS *out, struct SREGS *seg);
@end example

@subheading Description

This function simulates a software interrupt.  Note that, unlike the
@code{_go32_dpmi_*} functions, requests that go through @code{int86x}
and similar functions are normally processed by go32 to make it easier
for the programmer to use these functions.  For example, if a particular
routine takes a pointer in @code{ES:BX}, go32 expects you to put a
virtual pointer in @code{EBX} and it ignores @code{ES}.  This is mostly
because segments aren't used in protected mode the way they are in real
mode, so go32 takes care of the conversion for you - and it knows what
your segment selectors are anyway.

When the interrupt is invoked, the CPU registers are copied from
@var{in}.  After the interrupt, the CPU registers are copied to
@var{out}.  In addition, the segment registers are loaded from @var{seg}
and afterwards stored back into @var{seg}.

@xref{int86} @xref{intdos} @xref{bdos}

@subheading Return Value

The value of @code{EAX} is returned.

@subheading Example

@example
union REGS r;
struct SREGS s;
r.h.ah = 0x31;
r.h.dl = 'c';
r.x.si = si_val;
s.ds = ds_val;
int86x(0x21, &r, &r, &s);
@end example

@c ----------------------------------------------------------------------
@node intdos, intdosx, int86x, Alphabetical List

@heading @code{intdos}
@subheading Syntax

@example
#include <dos.h>

int intdos(union REGS *in, union REGS *out);
@end example

@subheading Description

This function is just like @code{int86x} (@xref{int86x}) except that
suitable default values are used for the segment registers and the
interrupt vector is 0x21.

@subheading Return Value

@code{EAX}

@c ----------------------------------------------------------------------
@node intdosx, _iob, intdos, Alphabetical List

@heading @code{intdosx}
@subheading Syntax

@example
#include <dos.h>

int intdosx(union REGS *in, union REGS *out, struct SREGS *s);
@end example

@subheading Description

This function is just like @code{int86x} (@xref{int86x}) except that the
interrupt vector is 0x21.

@subheading Return Value

@code{EAX}

@c ----------------------------------------------------------------------
@node _iob, isalnum, intdosx, Alphabetical List

@heading @code{_iob}

@subheading Description

This is an internal variable used to keep track of open @code{FILE*}
files.

@c ----------------------------------------------------------------------
@node isalnum, isalpha, _iob, Alphabetical List

@heading @code{isalnum}
@subheading Syntax

@example
#include <ctype.h>

int isalnum(int c);
@end example

@subheading Description

Tells if @var{c} is any letter or digit.

@subheading Return Value

Nonzero if @var{c} is a letter or digit, else zero.

@subheading Example

@c ----------------------------------------------------------------------
@node isalpha, isatty, isalnum, Alphabetical List

@heading @code{isalpha}
@subheading Syntax

@example
#include <ctype.h>

int isalpha(int c);
@end example

@subheading Description

Tells if @var{c} is a letter.

@subheading Return Value

Nonzero if @var{c} is a letter, else zero.

@c ----------------------------------------------------------------------
@node isatty, iscntrl, isalpha, Alphabetical List

@heading @code{isatty}
@subheading Syntax

@example
#include <osfcn.h>

int isatty(int fd);
@end example

@subheading Description

Tells if the file descriptor refers to a physical device or a disk file.

@subheading Return Value

Nonzero if @var{fd} is a device, zero if it is a disk file.

@subheading Example

@example
if (isatty(1))
  fflush(stdout);
@end example

@c ----------------------------------------------------------------------
@node iscntrl, isdigit, isatty, Alphabetical List

@heading @code{iscntrl}
@subheading Syntax

@example
#include <ctype.h>

int iscntrl(int c);
@end example

@subheading Description

Tells if @var{c} is a control character.

@subheading Return Value

Nonzero if @var{c} is a control character, else zero.

@c ----------------------------------------------------------------------
@node isdigit, isgraph, iscntrl, Alphabetical List

@heading @code{isdigit}
@subheading Syntax

@example
#include <ctype.h>

int isdigit(int c);
@end example

@subheading Description

Tells if @var{c} is a digit.

@subheading Return Value

Nonzero if @var{c} is a digit, else zero.

@c ----------------------------------------------------------------------
@node isgraph, islower, isdigit, Alphabetical List

@heading @code{isgraph}
@subheading Syntax

@example
#include <ctype.h>

int isgraph(int c);
@end example

@subheading Description

Tells if @var{c} is a visible printing character.  Space is not
included.

@subheading Return Value

Nonzero if @var{c} is a visible printing character, else zero.

@c ----------------------------------------------------------------------
@node islower, isprint, isgraph, Alphabetical List

@heading @code{islower}
@subheading Syntax

@example
#include <ctype.h>

int islower(int c);
@end example

@subheading Description

Tells if @var{c} is lower case or not.

@subheading Return Value

Nonzero if @var{c} is lower case, else zero.

@c ----------------------------------------------------------------------
@node isprint, ispunct, islower, Alphabetical List

@heading @code{isprint}
@subheading Syntax

@example
#include <ctype.h>

int isprint(int c);
@end example

@subheading Description

Tells if @var{c} is a printing character, which includes the space
character.

@subheading Return Value

Nonzero if @var{c} is a printing character, else zero.

@c ----------------------------------------------------------------------
@node ispunct, isspace, isprint, Alphabetical List

@heading @code{ispunct}
@subheading Syntax

@example
#include <ctype.h>

int ispunct(int c);
@end example

@subheading Description

Tells if @var{c} is any printing character except space and those
indicated by @code{isalnum}.

@subheading Return Value

Nonzero if @var{c} is punctuation, else zero.

@c ----------------------------------------------------------------------
@node isspace, isupper, ispunct, Alphabetical List

@heading @code{isspace}
@subheading Syntax

@example
#include <ctype.h>

int isspace(int c);
@end example

@subheading Description

Tells if @var{c} is whitespace, that is, carriage return, newline, form
feed, tab, vertical tab, or space.

@subheading Return Value

Nonzero if @var{c} is whitespace, else zero.

@c ----------------------------------------------------------------------
@node isupper, isxdigit, isspace, Alphabetical List

@heading @code{isupper}
@subheading Syntax

@example
#include <ctype.h>

int isupper(int c);
@end example

@subheading Description

Tells if @var{c} is an upper case character or not.

@subheading Return Value

Nonzero if @var{c} is upper case, else zero.

@c ----------------------------------------------------------------------
@node isxdigit, kbhit, isupper, Alphabetical List

@heading @code{isxdigit}
@subheading Syntax

@example
#include <ctype.h>

int isxdigit(int c);
@end example

@subheading Description

Tells if @var{c} is a valid hexidecimal digit or not.  This includes
@code{[0-9a-fA-f]}.

@subheading Return Value

Nonzero if @var{c} is a hex digit, else zero.

@c ----------------------------------------------------------------------
@node kbhit, kill, isxdigit, Alphabetical List

@heading @code{kbhit}
@subheading Syntax

@example
#include <pc.h>

int kbhit(void);
@end example

@subheading Description

If the user has hit a key, this function will detect it.  This function
is very fast when there is no key waiting, so it may be used inside
loops as needed.

@subheading Return Value

Nonzero if a key has been hit, else zero.

@subheading Example

@example
while (!kbhit())
  do_stuff();
@end example

@c ----------------------------------------------------------------------
@node kill, labs, kbhit, Alphabetical List

@heading @code{kill}

@subheading Description

This function does nothing.  It exists to assist in porting Unix
programs.

@c ----------------------------------------------------------------------
@node labs, ldexp, kill, Alphabetical List

@heading @code{labs}
@subheading Syntax

@example
#include <stdlib.h>

long labs(long x);
@end example

@subheading Description

This function takes the absolute value of @var{x}.  @xref{abs}

@subheading Return Value

|@var{x}|

@c ----------------------------------------------------------------------
@node ldexp, ldiv, labs, Alphabetical List

@heading @code{ldexp}
@subheading Syntax

@example
#include <math.h>

double ldexp(double val, int exp);
@end example

@subheading Return Value

This function returns @var{val} * 2 ** @var{exp}.

@subheading Example

@example
ldexp(3.5,4) == 3.5 * 16 == 56.0
@end example

@c ----------------------------------------------------------------------
@node ldiv, link, ldexp, Alphabetical List

@heading @code{ldiv}
@subheading Syntax

@example
#include <stdlib.h>

ldiv_t ldiv(long numerator, long denomonator);
@end example

@subheading Description

Returns the quotient and remainder of the division @var{numberator}
divided by @var{denomonator}.  The return type is as follows:

@example
typedef struct @{
  long quot;
  long rem;
@} ldiv_t;
@end example

@subheading Return Value

The results of the division are returned.

@subheading Example

@example
ldiv_t l = div(42, 3);
printf("42 = %ld x 3 + %ld\n", l.quot, l.rem);
@end example

@c ----------------------------------------------------------------------
@node link, localtime, ldiv, Alphabetical List

@heading @code{link}
@subheading Syntax

@example
#include <osfcn.h>

int link(const char *exists, const char *new);
@end example

@subheading Description

Because of limitations of MS-DOS, this function doesn't really link two
files together.  However, it simulates a real @code{link} by copying the
file at @var{exists} to @var{new}.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
link("foo.c", "foo.bak");
@end example

@c ----------------------------------------------------------------------
@node localtime, lock, link, Alphabetical List

@heading @code{localtime}
@subheading Syntax

@example
#include <time.h>

struct tm *localtime(const time_t *tod);
@end example

@subheading Description

Converts the time represented by @var{tod} into a structure, correcting
for the local timezone.  @xref{gmtime}

@subheading Return Value

A pointer to a static structure which is overridden with each call.

@c ----------------------------------------------------------------------
@node lock, longjmp, localtime, Alphabetical List

@heading @code{lock}
@subheading Syntax

@example
#include <io.h>

int lock(int fd, long offset, long length);
@end example

@subheading Description
Locks a region in file @var{fd} using MS-DOS file sharing interface.
The region of @var{length} bytes, starting from @var{offset}, will
become entirely inaccessible to other processes. If multiple locks
are used on a single file they must be non-overlapping. The lock
must be removed before the file is closed.

This function will fail unless SHARE, or a network software
providing similar interface, is installed. This function is
compatible with Borland C++ function of the same name.

@xref{unlock}.

@subheading Return Value
Zero if successful, nonzero if not.

@c ----------------------------------------------------------------------
@node longjmp, longjmperror, lock, Alphabetical List

@heading @code{longjmp}
@subheading Syntax

@example
#include <setjmp.h>

void longjmp(jmp_buf env, int val);
@end example

@subheading Description

This function reverts back to a CPU state that was stored in @var{env}
by @code{setjmp} (@xref{setjmp}).  The state includes all CPU registers,
so any variable in a register when @code{setjmp} was called will be
preserved, and all else will be indeterminate.

The value passed as @var{val} will be the return value of @code{setjmp}
when it resumes processing there.  If @var{val} is zero, the return
value will be one.

@subheading Return Value

This function does not return.

@subheading Example

@example
jmp_buf j;
if (setjmp(j))
  return;
do_something();
longjmp(j);
@end example

@c ----------------------------------------------------------------------
@node longjmperror, lseek, longjmp, Alphabetical List

@heading @code{longjmperror}
@subheading Syntax

@example
void longjmperr(void);
@end example

@subheading Description

This function is internal and is used by setjmp and longjmp when they
detect an invalid longjmp request.

@subheading Return Value

None.

@c ----------------------------------------------------------------------
@node lseek, __main, longjmperror, Alphabetical List

@heading @code{lseek}
@subheading Syntax

@example
#include <osfcn.h>

long lseek(nit fd, long offset, int whence);
@end example

@subheading Description

This function moves the file pointer for @var{fd} according to
@var{mode}:

@table @code

@item SEEK_SET

The file pointer is moved to the offset specified.

@item SEEK_CUR

The file pointer is moved relative to its current position.

@item SEEK_END

The file pointer is moved to a position @var{offset} bytes from the end
of the file.  The offset is usually nonpositive in this case.

@end table

@subheading Return Value

The new offset is returned.

@subheading Example

@example
lseek(fd, 12, SEEK_CUR); /* skip 12 bytes */
@end example

@c ----------------------------------------------------------------------
@node __main, malloc, lseek, Alphabetical List

@heading @code{__main}

@subheading Description

This function is used internally to initialize the application, and
should not be directly called by the programmer.

@c ----------------------------------------------------------------------
@node malloc, memccpy, __main, Alphabetical List

@heading @code{malloc}
@subheading Syntax

@example
#include <stdlib.h>

void *malloc(size_t size);
@end example

@subheading Description

This function allocates a chunk of memory from the heap large enough to
hold any object that is @var{size} bytes in length.  This memory must be
returned to the heap with @code{free} (@xref{free}).

@subheading Return Value

A pointer to the allocated memory, or @code{NULL} if there isn't enough
free memory to satisfy the request.

@subheading Example

@example
char *c = (char *)malloc(100);
@end example

@c ----------------------------------------------------------------------
@node memccpy, memchr, malloc, Alphabetical List

@heading @code{memccpy}
@subheading Syntax

@example
#include <string.h>

void *memccpy(void *dest, const void *source, int ch, size_t num);
@end example

@subheading Description

This function copies at most @var{num} bytes from @var{source} to
@var{dest}, stopping if the character @var{ch} is copied.

@subheading Return Value

A pointer to the character after @var{ch}, if it was found, else
@code{NULL}.

@subheading Example

@example
char buf[20];
memccpy(buf, "hello!", 'l', 20);
@end example

@c ----------------------------------------------------------------------
@node memchr, memcmp, memccpy, Alphabetical List

@heading @code{memchr}
@subheading Syntax

@example
void *memchr(const void *string, int ch, size_t num);
@end example

@subheading Description

This function searches @var{num} bytes starting at @var{string}, looking
for the first occurence of @var{ch}.

@subheading Return Value

A pointer to the first match, or @code{NULL} if it wasn't found.

@subheading Example

@example
if (memchr(path, '/', strlen(path))
  do_slash();
@end example

@c ----------------------------------------------------------------------
@node memcmp, _memcpy, memchr, Alphabetical List

@heading @code{memcmp}
@subheading Syntax

@example
#include <string.h>

int memcmp(const void *s1, const void *s2, size_t num);
@end example

@subheading Description

This function compares two regions of memory, at @var{s1} and @var{s2},
for @var{num} bytes.

@subheading Return Value

@table @asis

@item zero

s1 == s2

@item positive

s1 > s2

@item negative

s1 < s2

@end table

@c ----------------------------------------------------------------------
@node _memcpy, memcpy, memcmp, Alphabetical List

@heading @code{_memcpy}
@subheading Syntax

@example
#include <string.h>

void *_memcpy(void *dest, const void *src, int num);
@end example

@subheading Description

This function is just like @code{memcpy} (@xref{memcpy}), but it doesn't
use the i386 @code{movs} opcode, in case the source and destination are
on memory pages that can't reside in the system at the same time.  This
is used primarily for screen to screen copies of the graphics screen, in
case the two regions are in different graphics windows.

@subheading Return Value

@var{dest}

@c ----------------------------------------------------------------------
@node memcpy, memmove, _memcpy, Alphabetical List

@heading @code{memcpy}
@subheading Syntax

@example
#include <string.h>

void *memcpy(void *dest, const void *src, int num);
@end example

@subheading Description

This function copies @var{num} bytes from @var{source} to @var{dest}.

@subheading Return Value

@var{dest}

@subheading Example

@example
memcpy(buffer, temp_buffer, BUF_MAX);
@end example

@c ----------------------------------------------------------------------
@node memmove, memset, memcpy, Alphabetical List

@heading @code{memmove}
@subheading Syntax

@example
#include <string.h>

void *memmove(void *dest, const void *source, int num);
@end example

@subheading Description

This function copies @var{num} bytes from @var{source} to @var{dest}.
The copy is done in such a way that if the two regions overlap, the
source is always read before that byte is changed by writing to the
destination.

@subheading Return Value

@var{dest}

@subheading Example

@example
memmove(buf+1, buf, 99);
memmove(buf, buf+1, 99);
@end example

@c ----------------------------------------------------------------------
@node memset, mkdir, memmove, Alphabetical List

@heading @code{memset}
@subheading Syntax

@example
#include <string.h>

void *memset(void *buffer, int ch, size_t num);
@end example

@subheading Description

This function stores @var{num} copies of @var{ch}, starting at
@var{buffer}.  This is often used to initialize objects to a known
value.

@subheading Return Value

@var{buffer}

@subheading Example

@example
struct tm t;
memset(&t, 0, sizeof(t));
@end example

@c ----------------------------------------------------------------------
@node mkdir, mkfifo, memset, Alphabetical List

@heading @code{mkdir}
@subheading Syntax

@example
#include <osfcn.h>

int mkdir(const char *path, int mode);
@end example

@subheading Description

This function creates a subdirectory.  The @var{mode} field is ignored
under MS-DOS.

@subheading Return Value

Zero if the subdirectory was created, nonzero on failure.

@subheading Example

@example
mkdir("/usr/tmp");
@end example

@c ----------------------------------------------------------------------
@node mkfifo, mknod, mkdir, Alphabetical List

@heading @code{mkfifo}

@subheading Description

This function is provided only to assist in porting from Unix.  It
always returns an error condition.

@c ----------------------------------------------------------------------
@node mknod, mkstemp, mkfifo, Alphabetical List

@heading @code{mknod}

@subheading Description

This function is provided only to assist in porting from Unix.  It
always returns an error condition.

@c ----------------------------------------------------------------------
@node mkstemp, mktemp, mknod, Alphabetical List

@heading @code{mkstemp}
@subheading Syntax

@example
#include <stdio.h>

int mkstemp(char *template);
@end example

@subheading Description

@var{template} is a file specification that ends with six trailing
@code{X} characters.  This function replaces the @code{XXXXXX} with a
set of characters such that the resulting file name names a nonexisting
file.  It then creates and opens the file.

Note that since MS-DOS is limited to eight characters for the file name,
and since none of the @code{X}'s get replaced by a dot, you can only
have two additional characters before the @code{X}'s.

@subheading Return Value

The open file descriptor.

@subheading Example

@example
int fd = mkstemp("/tmp/ccXXXXXX");
@end example

@c ----------------------------------------------------------------------
@node mktemp, mktime, mkstemp, Alphabetical List

@heading @code{mktemp}
@subheading Syntax

@example
#include <stdio.h>

char *mktemp(char *template);
@end example

@subheading Description

@var{template} is a file specification that ends with six trailing
@code{X} characters.  This function replaces the @code{XXXXXX} with a
set of characters such that the resulting file name names a nonexisting
file.

Note that since MS-DOS is limited to eight characters for the file name,
and since none of the @code{X}'s get replaced by a dot, you can only
have two additional characters before the @code{X}'s.

@subheading Return Value

The resulting filename.

@subheading Example

@example
char template[] = "/tmp/ccXXXXXX";
mktemp(template);
FILE *q = fopen(template, "w");
@end example

@c ----------------------------------------------------------------------
@node mktime, modf, mktemp, Alphabetical List

@heading @code{mktime}
@subheading Syntax

@example
#include <time.h>

time_t mktime(struct tm *tptr);
@end example

@subheading Description

This function converts a time structure into the number of seconds since
00:00:00 GMT 1/1/1970.  It also attempts to normalize the fields of
@var{tptr}.

@subheading Return Value

The resulting time, or -1 if the time in @var{tptr} cannot be described
in that format.

@c ----------------------------------------------------------------------
@node modf, morecore, mktime, Alphabetical List

@heading @code{modf}
@subheading Syntax

@example
#include <math.h>

double modf(double x, double *pint);
@end example

@subheading Description

This function decomposes @var{x} into it's integer part (*@var{pint})
and it's fractional part (return value) such that the two have the same
sign and add up to @var{x}.

@subheading Return Value

The fractional part.

@subheading Example

@example
double f, i;
f = modf(2.3, &i);
/* f == 0.3, i == 2.0 */
@end example

@c ----------------------------------------------------------------------
@node morecore, movedata, modf, Alphabetical List

@heading @code{morecore}

@subheading Description

This is an internal function used by @code{malloc} (@xref{malloc}).

@c ----------------------------------------------------------------------
@node movedata, nlist, morecore, Alphabetical List

@heading @code{movedata}
@subheading Syntax

@example
#include <go32.h>

void movedata(unsigned source_selector, unsigned source_offset,
              unsigned dest_selector, unsigned dest_offset,
              size_t length);
@end example

@subheading Description

This function allows the caller to directly transfer information between
conventional and linear memory, and among each as well.  The selectors
passed are @emph{not} segment values like in DOS.  They are protected
mode selectors that can be obtained by the @code{_go32_my_ds} and
@code{_go32_conventional_mem_selector} functions (@xref{_go32_my_ds}
@xref{_go32_conventional_mem_selector}).  The offsets are linear
offsets.  If the selector is for the program's data area, this offset
corresponds to the address of a buffer (like @code{(int)&something}).  If the
selector is for the conventional memory area, the offset is the physical
address of the memory, which can be computed from a traditional
segment/offset pair as @code{segment}*16+@code{offset}.  For example,
the color text screen buffer is at offset 0xb8000.

@subheading Return Value

None.

@subheading Example

@example
short blank_row_buf[ScreenCols()];
/* scroll screen */
movedata(_go32_conventional_mem_selector(), 0xb8000 + ScreenCols()*2,
         _go32_conventional_mem_selector(), 0xb8000,
         ScreenCols() * (ScreenRows()-1) * 2);
/* fill last row */
movedata(_go32_my_ds, (int)blank_row_buf,
         _go32_conventional_mem_selector(),
            0xb8000 + ScreenCols()*(ScreenRows()-1)*2,
          ScreenCols() * 2);
@end example